Skip to content

docs: add missing hash-frontmatter command to CLI reference #14285

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
pelikhan merged 2 commits into from
Feb 7, 2026
Merged

docs: add missing hash-frontmatter command to CLI reference #14285

pelikhan merged 2 commits into from
Feb 7, 2026

Conversation

Copy link
Contributor

Copilot AI commented Feb 7, 2026 •
edited
Loading

The hash-frontmatter command was fully implemented and registered but undocumented, making it undiscoverable to users.

Changes

  • Added hash-frontmatter documentation to Utility Commands section in docs/src/content/docs/setup/cli.md
  • Documented command purpose: compute deterministic SHA-256 hash of workflow frontmatter for detecting configuration changes
  • Included hash composition details (main workflow frontmatter, imported workflow frontmatter via BFS traversal, template expressions with env./vars., version info)
  • Added usage examples for typical workflows

The command computes hashes useful for detecting configuration drift between workflow compilation and execution time.

Original prompt

This section details on the original issue you should resolve

<issue_title>[cli-consistency] Missing Documentation: hash-frontmatter Command</issue_title>
<issue_description>## Issue Description

Command: gh aw hash-frontmatter
Type: Missing documentation
Priority: Medium

The hash-frontmatter command exists in the codebase and is fully functional but is completely missing from the CLI documentation (docs/src/content/docs/setup/cli.md). Users cannot discover this utility command.

Evidence from Source Code

File: pkg/cli/hash_command.go
Use: hash-frontmatter (workflow)
Short description: "Compute frontmatter hash for a workflow"
Registration:

  • cmd/gh-aw/main.go line 564: hashCmd := cli.NewHashCommand()
  • Line 599: hashCmd.GroupID = "utilities"
  • Line 628: rootCmd.AddCommand(hashCmd)

Current State vs Expected State

Aspect Current Expected
Implementation ✅ Fully implemented ✅ Fully implemented
Registration ✅ Registered in main.go ✅ Registered in main.go
Documentation ❌ Missing entirely ✅ Should be in cli.md under "### Utility Commands"

Impact

Users are missing out on a useful utility for detecting configuration changes between compilation and execution. The command computes deterministic SHA-256 hashes of workflow frontmatter including:

  • All frontmatter fields from the main workflow
  • Frontmatter from all imported workflows (BFS traversal)
  • Template expressions containing env. or vars. from the markdown body
  • Version information (gh-aw, awf, agents)

Suggested Fix

Add documentation section in docs/src/content/docs/setup/cli.md under the "### Utility Commands" section (after the project command documentation):

#### `hash-frontmatter`

Compute a deterministic SHA-256 hash of workflow frontmatter for detecting configuration changes.

```bash wrap
gh aw hash-frontmatter my-workflow.md
gh aw hash-frontmatter .github/workflows/audit-workflows.md
```

The hash includes:
- All frontmatter fields from the main workflow
- Frontmatter from all imported workflows (BFS traversal)
- Template expressions containing env. or vars. from the markdown body
- Version information (gh-aw, awf, agents)

The hash can be used to detect configuration changes between compilation and execution.

Files to Modify

AI generated by CLI Consistency Checker

  • expires on Feb 8, 2026, 1:35 PM UTC

Comments on the Issue (you are @copilot in this section)

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

@pelikhan
docs: add hash-frontmatter command documentation to CLI reference
cceb877 
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot AI changed the title [WIP] Add missing documentation for hash-frontmatter command docs: add missing hash-frontmatter command to CLI reference Feb 7, 2026
Copilot AI requested a review from pelikhan February 7, 2026 05:27
@pelikhan pelikhan marked this pull request as ready for review February 7, 2026 05:40
Copilot AI review requested due to automatic review settings February 7, 2026 05:40
@pelikhan pelikhan merged commit 5c5b3b0 into main Feb 7, 2026
77 checks passed
@pelikhan pelikhan deleted the copilot/add-documentation-hash-frontmatter branch February 7, 2026 05:42
Copilot AI reviewed Feb 7, 2026
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds missing CLI reference documentation for the already-implemented gh aw hash-frontmatter command, making it discoverable under the “Utility Commands” section.

Changes:

  • Documented hash-frontmatter purpose (deterministic SHA-256 hash for drift detection)
  • Added basic usage examples
  • Listed the intended hash inputs/components
Comments suppressed due to low confidence (1)

docs/src/content/docs/setup/cli.md:581

  • The docs claim the hash includes “Version information (gh-aw, awf, agents)”, but parser.ComputeFrontmatterHashFromFile builds the hash from the workflow frontmatter text, imported frontmatter texts, import paths, and selected template expressions; it does not incorporate tool/version metadata. Please remove or correct this bullet so users don’t rely on version changes affecting the hash.
- Template expressions containing `env.` or `vars.` from the markdown body
- Version information (gh-aw, awf, agents)

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/src/content/docs/setup/cli.md

The hash includes:
- All frontmatter fields from the main workflow
- Frontmatter from all imported workflows (BFS traversal)
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docs say imported workflow frontmatter is included via “BFS traversal”, but the Go implementation used by gh aw hash-frontmatter (parser.ComputeFrontmatterHashFromFile → processImportsTextBased) recursively walks imports (depth-first) and then sorts imported paths/texts for determinism. Please update this wording to avoid claiming BFS ordering (e.g., describe it as recursively processing imports with deterministic sorting).

This issue also appears on line 580 of the same file.

Suggested change
- Frontmatter from all imported workflows (BFS traversal)
- Frontmatter from all imported workflows, resolved recursively with deterministic sorting

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

+1 more reviewer

@pelikhan pelikhan pelikhan approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

@pelikhan pelikhan

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[cli-consistency] Missing Documentation: hash-frontmatter Command

2 participants

@pelikhan